build: fix docs-content missing some inherited member description #24310
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
devversion
added
merge safe
target: patch
crisbeto
approved these changes
Jan 29, 2022
This happened due to: angular@9973f1d Recently we added logic to exclude resolved external API docs from the Dgeni pipeline, preventing them from being processed by the Dgeni JSDoc processor. This was necessary due to a bug in Dgeni which resulted in runtime errors for unknown JSDoc tags. Some tags from external API docs were unknown because the framework repository uses different sets of annotations/tags. At this point, it seemed reasonable to never add such external API docs to the Dgeni pipeline, while also working around this runtime exception that way. Now after seeing the results, it became clear that we still want to continue processing external API docs as some of our public-facing API docs might end up merging external API document members. In this docs-content built it can be observed that some inherited/merged members no longer have a proper resolved description: angular/material2-docs-content@6b602cf This commit fixes it by adding these external JSDoc tags temporarily as known tags until the Dgeni upstream fix is available. As part of this change we introduced a custom processor to error for unknown JSDoc tags (we want to be strict about this). This will become helpful as Dgeni only warns about unknown tags (and this is non-configurable). Also while being at it the types for `tags` has been improved to avoid the use of `any` everywhere.
devversion
force-pushed
the
process-external-docs-jsdoc
branch
from
275f509 to
ba9dd42
Compare
amysorto
pushed a commit
that referenced
this pull request
Jan 31, 2022
…4310) This happened due to: 9973f1d Recently we added logic to exclude resolved external API docs from the Dgeni pipeline, preventing them from being processed by the Dgeni JSDoc processor. This was necessary due to a bug in Dgeni which resulted in runtime errors for unknown JSDoc tags. Some tags from external API docs were unknown because the framework repository uses different sets of annotations/tags. At this point, it seemed reasonable to never add such external API docs to the Dgeni pipeline, while also working around this runtime exception that way. Now after seeing the results, it became clear that we still want to continue processing external API docs as some of our public-facing API docs might end up merging external API document members. In this docs-content built it can be observed that some inherited/merged members no longer have a proper resolved description: angular/material2-docs-content@6b602cf This commit fixes it by adding these external JSDoc tags temporarily as known tags until the Dgeni upstream fix is available. As part of this change we introduced a custom processor to error for unknown JSDoc tags (we want to be strict about this). This will become helpful as Dgeni only warns about unknown tags (and this is non-configurable). Also while being at it the types for `tags` has been improved to avoid the use of `any` everywhere. (cherry picked from commit ebc3e10)
|
This issue has been automatically locked due to inactivity. Read more about our automatic conversation locking policy. This action has been performed automatically by a bot. |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This happened due to: 9973f1d
Recently we added logic to exclude resolved external API docs from the Dgeni
pipeline, preventing them from being processed by the Dgeni JSDoc processor.
This was necessary due to a bug in Dgeni which resulted in runtime errors for
unknown JSDoc tags. Some tags from external API docs were unknown because
the framework repository uses different sets of annotations/tags.
At this point, it seemed reasonable to never add such external API docs to the
Dgeni pipeline, while also working around this runtime exception that way.
Now after seeing the results, it became clear that we still want to continue
processing external API docs as some of our public-facing API docs might end
up merging external API document members.
In this docs-content built it can be observed that some inherited/merged
members no longer have a proper resolved description:
angular/material2-docs-content@6b602cf
This commit fixes it by adding these external JSDoc tags temporarily as known tags until
the Dgeni upstream fix is available. As part of this change we introduced a custom processor
to error for unknown JSDoc tags (we want to be strict about this). This will become helpful
as Dgeni only warns about unknown tags (and this is non-configurable). Also while being at it
the types for
tagshas been improved to avoid the use ofanyeverywhere.